Browsing {json:api} documents as a human

TLDR: I wrote a tool to visualise {json:api} documents

There are good and bad things about {json:api}. For example, their website covers most of what you’ll need and is well illustrated with examples. Yet if you need anything else it’s hard to find it because of its generic name: search results always yield false-positives.

Another great thing about {json:api} is its serialisation format. A quote from their website:

JSON API flattens the entire graph of objects at the top level. This means that if the same “people” are referenced from different kinds of objects (say, the author of both posts and comments), this format ensures that there is only a single representation of each person document in the payload.

This is great for machines but is not as intuitive for humans as, say, recursively nesting child entities to express a relationship. Even though most of the humans looking at a json file are going to be developers we shouldn’t neglect the need to be able to quickly understand the relationships between entities in a document.

With no extra tools, in order to “traverse” relationships you’d need to copy a reference ID and use search to jump between all the matches until you find the referenced entity. Doing that you often lose context of what you’re looking at.

In an open-source spirit instead of complaining about the situation I decided to build a tool to ease the problem. {json:api} document viewer is an open source tool that visualises relationships between entities in a {json:api} document. It’s a single-page, client-side only (your documents are not sent to any server), react-based application that starts at the root document and allows you to browse through a {json:api} document without losing the context.